Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 4 - Dialog Manager Reference / Dialog Manager Functions

Creating Alerts /

CautionAlert

CHANGED WITH THE APPEARANCE MANAGER

Displays an alert box with a caution icon in its upper-left corner (or, if appropriate for the alert stage, to play an alert sound instead of or in addition to displaying the alert box).

pascal short CautionAlert (
                     short alertID,
                     ModalFilterUPP modalFilter);

alertID

The resource ID of an alert resource and extended alert resource. If the alert resource is missing, the Dialog Manager returns to your application without creating the requested alert.

modalFilter

A universal procedure pointer for a filter function that responds to events not handled by the ModalDialog function. If you set this parameter to nil, the Dialog Manager uses the standard event filter function.

function result

If no alert box is to be drawn at the current alert stage, CautionAlert returns -1; otherwise, it uses NewDialog to create and display the alert box and returns the item hit; see "Alert Button Constants".

DISCUSSION

The CautionAlert function is the same as the Alert function except that, before drawing the items in the alert box, CautionAlert draws the caution icon in the upper-left corner. The caution icon has resource ID 2, which you can also specify with the constant kCautionIcon. By default, the Dialog Manager uses the standard caution icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 2.

Use a caution alert to alert the user of an operation that may have undesirable results if it's allowed to continue. Give the user the choice of continuing the action (by clicking an OK button) or stopping it (by clicking a Cancel button).

IMPORTANT

Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the CautionAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call CautionAlert.

SEE ALSO

NoteAlert.

StopAlert.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

CautionAlert only reads in the resource ID of an alert resource, not an extended alert resource.